<html>
<body>

<p>Core classes of the Args4J command line parser.</p>

<h1>What is Args4J?</h1>

    <p>
        Args4J is a command line parser. 
        As such, its job is to parse the String-array passed to the <code>main()</code> method and 
        transfer the values to a Java object, which includes type conversion. 
        The entry point into this parsing is the <code>CmdLineParser</code> class, 
        with its <code>parse()</code> method.
    </p>

    <p>Args4J must know the mapping between the flag from the command line and the target for the value.
    There are many ways to use Args4J:</p>
    
    <ul>
        <li>place an <code>@Option</code> or <code>@Argument</code> annotation at a setter or on a field</li>
        <li>provide a XML configuration file</li>
        <li>make all fields publicly available</li>
    </ul> 
    
    <p>Depending on what you want, you may have perform a configuration step before parsing.</p>


<h1>Examples</h1>

<p><code>java Main -text newText</code></p>

<p>The typical use involves writing a small bean class and providing the annotations.</p>
<p>This feature is available since the first Args4J release:</p>

<pre>
public class Bean {
   {@literal @}Option(name="-text")
    String text;
}
public class Main {
    public static void main(String[] args) throws CmdLineException {
        Object bean = new Bean();
        CmdLineParser parser = new CmdLineParser(bean);
        parser.parse(args);
    }
}
</pre>


<p>An easy way to initialize fields without touching the bean source code is to use the <code>FieldParser</code>.</p>

<p>The <code>FieldParser</code> scans all fields of bean class (including inheritance), and makes them publicly available as options with a <code>-</code> prefix in the name.</p>

<p>This feature is available since Args4J release 2.0.16:</p>

<code><pre>
public class Bean {
    String text;
}
public class Main {
    public static void main(String[] args) throws CmdLineException {
        Object bean = new Bean();
        CmdLineParser parser = new CmdLineParser(null);
        new FieldParser().parse(parser, bean);
        parser.parse(args);
    }
}
</pre></code>

<p>While the <code>FieldParser</code> is easier to use, the <code>XmlParser</code> supports more features.</p>
<p>That said, it supports all features which are available via annotations: usage text, specifying handlers, and more. You have to provide an XML <code>InputSource</code> or a URL to the XML file.</p>

<p>This feature is available since Args4J release 2.0.16:</p>

<code><pre>
public class Bean {
    String text;
}
public class Main {
    public static void main(String[] args) throws CmdLineException {
        Object bean = new Bean();
        CmdLineParser parser = new CmdLineParser(null);
        new XmlParser().parse(getClass().getResource(bean.getClass().getName() + ".xml"), parser, bean);
        parser.parse(args);
    }
}
&lt;args>
  &lt;option field="text" name="-text" usage="Output text"/>
&lt;/args>
</pre></code>

</body>
</html>